home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 21 / Cream of the Crop 21 (Terry Blount) (October 1996).iso / bbs / develop.zip / HEADERS.DOC < prev    next >
Text File  |  1993-04-27  |  21KB  |  413 lines
  1.   WARNING:  This document is subject to change at any time.  Any changes made
  2.   will be indicated by a vertical bar (|) in column 1 of the file.
  3.  
  4. | Last update: 04/27/93
  5.  
  6. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  7.  
  8.   The following is the standard message header (128 byte block) with only
  9.   slight modifications:
  10.  
  11.   typedef struct {
  12.     char    Status;
  13.     bassngl MsgNumber;
  14.     bassngl RefNumber;
  15.     char    NumBlocks;      <- see bit #7 of ExtendedStatus
  16.     char    Date[8];
  17.     char    Time[5];
  18.     char    ToField[25];
  19.     bassngl ReplyDate;
  20.     char    ReplyTime[5];
  21.     char    ReplyStatus;
  22.     char    FromField[25];
  23.     char    SubjField[25];
  24.     char    Password[12];
  25.     char    ActiveFlag;
  26.     char    EchoFlag;
  27.     char    Reserved1[4];    <- reserved was 6 bytes
  28.     char    ExtendedStatus;  <- new byte - 0 for compatibility, accept 32 also
  29.     char    Reserved2;       <- last of original reserved bytes
  30.   } msgheadertype;
  31.  
  32.   The message base format remains almost 100% identical to the PCBoard v14.x
  33.   standard.  In fact, it remains 100% compatible having just one byte
  34.   different, which was not previously used by PCBoard.
  35.  
  36.   The byte at offset 126 (i.e.  the 127th byte of the 128 byte header) has a
  37.   new function.  It is now used to indicate that extended header information
  38.   will be found in the body of the message.
  39.  
  40.   The byte, referenced as ExtendedStatus above, will contain a 0 by default to
  41.   indicate that no extended header information is available.  A value of 32
  42.   will also be accepted to indicate the same thing since some programs may be
  43.   placing a space instead of a null character in the reserved byte(s).
  44.  
  45.   If ExtendedStatus is not equal to 0 or 32 then it is assumed that extended
  46.   header information is available, however, a follow-up check of the message
  47.   body will determine the true existence, or lack thereof, of such information.
  48.  
  49.   For speed purposes, ExtendedStatus will be divided into 'bits' as follows:
  50.  
  51.     bit 0 = extended header has TO information
  52.     bit 1 = extended header has FROM information
  53.     bit 2 = extended header has SUBJECT information
  54.     bit 3 = extended header has CARBON LIST TO information
  55.     bit 4 = extended header has ATTACHED FILE information
  56.     bit 5 = ignore - this bit is equal to decimal 32
  57.     bit 6 = extended header has either REQRR or ACKRR information
  58.     bit 7 = reserved for future use
  59.  
  60.   Bit 6 indicates that either an REQRR (request return receipt) or an ACKRR
  61.   (acknowledge return receipt) extended header is in the message.
  62.  
  63.   The following structure will be used within the contents of a message body
  64.   whenever an extended header is to be included:
  65.  
  66.   typedef struct {
  67.     int   Ident;        16639 (40FF hex)
  68. |   char  Function[7];  TO,TO2,FROM,FROM2,SUBJECT,ATTACH,LIST,ROUTE,ORIGIN,REQRR,ACKRR,ACKNAME,PACKOUT
  69.     char  Colon;        always set to ":"
  70.     char  Descript[60]; user name, subject, filename
  71.     char  Status;       NONE, READ (if LIST)
  72.     char  CarReturn;    0xE3 or 0x0D
  73.   } msgextendtype;
  74.  
  75.   There can be as many extended headers as desired.  In fact, no headers at all
  76.   is possible even though the ExtendedStatus from the message header told
  77.   PCBoard to expect to find one.  This, of course, has a negative impact on
  78.   efficiency (don't set the flag unless you really intend to put an extended
  79.   header in the body of the message) but maintains complete compatibility with
  80.   previous versions of PCBoard which totally ignored the values found where the
  81.   ExtendedStatus byte is now located.
  82.  
  83.   The first field, Ident, serves to indicate that a truly valid header is about
  84.   to follow.  Ident is an integer value of 40FFh.  Stored in the file it is
  85.   seen as an ascii 255 character followed by an @ character.
  86.  
  87.   Older software will not expect this extended header to be in there and will
  88.   display the header to the user.  The format of the information, however, is
  89.   such that it will be meaningful, albeit, somewhat annoying to see.
  90.  
  91. | The function of the header is written in english.  Right now the following
  92. | are valid values for PCBoard:  "TO     ", "TO2    ", "FROM ", "FROM2  ",
  93. | "SUBJECT", "ATTACH ", "LIST ", "ROUTE ", "ORIGIN ", "REQRR  ", "ACKRR  ",
  94. | "ACKNAME" and "PACKOUT".  Any other values are permissable but will be
  95. | ignored by PCBoard v15.0 unless and until future updates to PCBoard add
  96. | new-standards.
  97.  
  98.   The next character in the header is a colon which is then followed by the
  99.   appropriate text for the header.  For example, the header might be structured
  100.   like this:
  101.  
  102.      <255><@>SUBJECT:any subject you wish to put here, up to 60 characters
  103.  
  104.   Notice how an older program, which is not PCB v15.0-aware, will still display
  105.   something intelligible to the user who is reading the message.  Because the
  106.   entire text is in english the user will be faced with extra information that
  107.   is not utilized by the software he is using, but at the same time, the extra
  108.   information does not make his software incompatible or unusable.  This
  109.   protects the user's investment in software and time, especially if the author
  110.   is no longer supporting the program, or the user does not have time to switch
  111.   programs or upgrade to a newer package which may have more bells and whistles
  112.   than he cares to learn.
  113.  
  114.   Of course, older packages will not be able to take advantage of the added
  115.   functionality since the header information will be very difficult to enter
  116.   properly via the keyboard.  So, while remaining compatible with older
  117.   software, to take advantage of the new features a user will still have to
  118.   upgrade to a newer release of the package.
  119.  
  120.   The text for the header may be up to 60 bytes long.  If the Function is set
  121.   to "TO" then the header indicates a longer, or alternate, name should be used
  122.   when displaying the TO:  field of the message.  If the Function is set to
  123.   "LIST" then the header indicates the name of ONE of the users who is to
  124.   receive the message.  There may be more than one "LIST" header, in fact, it
  125.   is expected that any time you create a carbon copy list you will be sending
  126.   the message to two or more users.  If the Function is set to "FROM" then it
  127.   indicates a longer, or alternate, name should be displayed for the FROM:
  128.   field.  If set to "SUBJECT" then a longer, or alternate, subject is
  129.   displayed.  If set to "ATTACH" then the description field indicates the name
  130.   of the attached file.  If set to ROUTE then message routing information (for
  131.   netmail transfers) will be included.  If set to ORIGIN then the origin of the
  132.   message (for netmail transfers) will be included.  If set to REQRR then
  133.   PCBoard will generate a Return Receipt when the user reads the message
  134.   online.  Mail Doors will need to be enhanced to perform the same
  135.   functionaility.  If set to ACKRR this will indicate that an acknowledgement
  136.   to the Return Receipt is contained in the message.  One additional header,
  137.   the ACKNAME, will be included with ACKRR to complete the acknowledgement.
  138.  
  139.   The next byte is the extended header status byte.  To help guarantee that the
  140.   header is valid, there are only three possible values for this field.  They
  141.   are:  'N', and 'R'.  These values are used as follows:
  142.  
  143.      'N' indicates that there is no status - it is used just for verification
  144.      'R' indicates that a user in a CARBON COPY LIST has read the message
  145.  
  146.   The 'R' allows PCBPack to determine when all intended recepients have read
  147.   the message.  Each user is listed in a separate header and each user
  148.   therefore has a separate status byte to indicate when it has been read.  Once
  149.   all users have read the message it may then be deleted.
  150.  
  151.   Finally, the CarReturn byte is set to E3 hex.  This is the same character
  152.   that is normally used by PCBoard to indicate the end of a line.  By
  153.   terminating the header in this manner all non-v15.0-aware packages will be
  154.   able to properly display the entire header in a legible form.  The 0D hex
  155.   value is used by foreign systems (such as the Chinese version of PCBo